home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 003a / asmlib35.zip / EMSXMS.DOC < prev    next >
Text File  |  1993-01-20  |  13KB  |  408 lines
  1.  
  2. ******************** EXPANDED AND EXTENDED MEMORY **************************
  3.  
  4. ASMLIB's EMS subroutines detect and manipulate Expanded Memory hardware
  5. and software.  Expanded memory, when installed in any PC, can help solve
  6. many memory limitation problems.  Call IsEMS before using any other
  7. ASMLIB EMS subroutines.
  8.  
  9. EMS memory is allocated in blocks of 16k increments
  10.  
  11. Error codes returned by EMS functions are:
  12.  
  13.    AH = 0      no error
  14.    AH = 80h    error in memory manager software
  15.    AH = 81h    error in expanded memory hardware
  16.    AH = 84h    bad function code passed to memory manager
  17.    AH = 85h    no EMM handles available
  18.    AH = 89h    you tried to allocate zero pages
  19.  
  20.  
  21. ASMLIB also supports XMS-compatible extended memory.  You must call IsXMS
  22. to determine if XMS memory is available before using any ASMLIB XMS
  23. subroutines.
  24.  
  25. XMS memory is available on many 286 or better computers with a suitable
  26. driver.  On 286 computers, XMS memory will be much slower than EMS memory.
  27. XMS memory is not available on XT (or compatible) computers.
  28.  
  29. XMS memory is allocated in 1k increments
  30.  
  31. XMS error codes include:
  32.  
  33.    AH = 0                 no error
  34.    AH = 0A0h              all extended memory is allocated
  35.    AH = 0A1h              no handles available
  36.    AH = 0A2h, 0A3h, 0A5h  handle is invalid
  37.    AH = 0A4h, 0A6h        offset is invalid
  38.    AH = 0A7h              length is invalid
  39.  
  40.  
  41. ASMLIB's EMS and XMS subroutines were written with identical calling
  42. parameters and identical returned information for comparble EMS and XMS
  43. subroutines.  For example, AllocEMS and AllocXMS are both called with
  44. DX:AX = the number of bytes requested.
  45.  
  46.  
  47. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  48.  
  49. ALLOCEMS:   allocates EMS memory
  50. Source:     ems.asm
  51.  
  52. Call with:  DX:AX = number of bytes of memory to allocate
  53.  
  54.             EMS memory is allocated in 16k blocks.  AllocEMS will allocate
  55.             multiple blocks if nessesary.
  56.             NOTE: You must first use IsEMS to determine if Expanded
  57.             memory is installed.
  58.  
  59. Returns:    if CF = 0, BX = EMS handle
  60.             if CF = 1, AH = EMS error code
  61. Uses:       AX, BX, flags
  62. Example:    see example code at the end of this file
  63.  
  64.  
  65.  
  66. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  67.  
  68. ALLOCXMS:   allocates XMS memory
  69. Source:     xms.asm
  70.  
  71. Call with:  DX:AX = number of bytes of memory to allocate
  72.  
  73.             XMS memory is allocated in 1k blocks.  AllocXMS will allocate
  74.             multiple blocks if nessesary.
  75.             NOTE: You must first use IsXMS to determine if XMS Extended
  76.             memory is available.
  77.  
  78. Returns:    if CF = 0, BX = XMS handle
  79.             if CF = 1, AH = XMS error code
  80. Uses:       AX, BX, flags
  81. Example:    see example code at the end of this file
  82.  
  83.  
  84.  
  85. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  86.  
  87. EMGET:      copy data from EMS memory to system RAM
  88. Source:     emputget.asm ($emspage.asm)
  89.  
  90. Call with:  BX = EMS handle
  91.             ES:[DI] pointing to destination buffer
  92.             DS:[SI] pointing to 4-byte offset in EMS block
  93.             DX:AX = number of bytes to copy
  94. Returns:    if CF = 0, no error
  95.             if CF = 1, AH = EMS error code
  96. Uses:       AX, flags
  97. Example:    see example code at the end of this file
  98.  
  99.  
  100.  
  101. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  102.  
  103. EMMVER:     determines Expanded Memory Manager version
  104. Source:     emmver.asm
  105.  
  106. Call with:  no parameters
  107. Returns:    if CF = 1, AH = EMS error code
  108.             if CF = 0, AH = major version number
  109.                        AL = minor version number
  110. Uses:       AX, flags
  111. Example:
  112.  
  113. include  asm.inc
  114.  
  115. extrn    isems:proc, emmver:proc
  116.  
  117. .code
  118.          .
  119.          .
  120.          .
  121.          call   isems
  122.          jc     no_ems
  123.          call   emmver     ; get emm version
  124.          jc     ems_error
  125.          cmp    ah,4       ; version 4.x?
  126.          jb     version3x  ; nope, an older EMM version
  127.  
  128.  
  129.  
  130. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  131.  
  132. EMPUT:      copy data to EMS memory from system RAM
  133. Source:     emputget.asm ($emspage.asm)
  134.  
  135. Call with:  BX = EMS handle
  136.             ES:[DI] pointing to data to copy
  137.             DS:[SI] pointing to 4-byte offset in EMS block
  138.             DX:AX = number of bytes to copy
  139. Returns:    if CF = 0, no error
  140.             if CF = 1, AH = EMS error code
  141. Uses:       AX, flags
  142. Example:    see example code at the end of this file
  143.  
  144.  
  145.  
  146. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  147.  
  148. EMSFREE:    determine free EMS memory
  149. Source:     emsfree.asm
  150.  
  151. Call with:  no parameters
  152.  
  153.             EMSFree does not verify that EMS memory is installed; you should
  154.             call IsEMS to determine if EMS memory is installed before using
  155.             this subroutine.  Do not confuse this subroutine with FreeEMS,
  156.             which releases a previously allocated EMS block and handle.
  157.  
  158. Returns:    DX:AX = bytes of EMS memory available
  159. Uses:       AX, DX, flags
  160. Example:
  161.  
  162. include asm.inc
  163.  
  164. public  myprog
  165. extrn   isems:proc, emsfree:proc
  166.  
  167. .code
  168. myprog  proc
  169.         call    isems           ; see if EMS memory is installed
  170.         jc      nope
  171.         call    emsfree         ; is enough available?
  172.         .
  173.         .
  174.         .
  175.  
  176.  
  177. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  178.  
  179. EMSTOTAL:   determine total EMS memory installed
  180. Source:     emsfree.asm
  181.  
  182. Call with:  no parameters
  183.             EMSTotal does not verify that EMS memory is installed; you should
  184.             call IsEMS to determine if EMS memory is installed before using
  185.             this subroutine.
  186. Returns:    DX:AX = bytes of EMS memory installed
  187. Uses:       AX, DX, flags
  188. Example:
  189.  
  190. include asm.inc
  191.  
  192. public  myprog
  193. extrn   isems:proc, emstotal:proc
  194.  
  195. .code
  196. myprog  proc
  197.         call    isems           ; see if EMS memory is installed
  198.         jc      nope
  199.         call    emstotal        ; how much?
  200.         .
  201.         .
  202.         .
  203.  
  204.  
  205. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  206.  
  207. FREEEMS:    releases an EMS memory block and handle
  208. Source:     ems.asm
  209.  
  210. Call with:  BX = EMS handle
  211.  
  212.             NOTE: DOS does not release EMS memory when your program
  213.             returns to DOS.  Your program must close any open EMS handles
  214.             before quitting, or the EMS memory associated with the handles
  215.             will be unavailable to other programs.  Do not confuse this
  216.             subroutine with EMSFree, whick determines the EMS memory
  217.             available.
  218.  
  219. Returns:    if CF = 0, no error
  220.             if CF = 1, AH = EMS error code
  221. Uses:       AX, flags
  222. Example:    see example code at the end of this file
  223.  
  224.  
  225.  
  226. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  227.  
  228. FREEXMS:    releases an XMS memory block and handle
  229. Source:     xms.asm
  230.  
  231. Call with:  BX = XMS handle
  232.  
  233.             NOTE: DOS does not release XMS memory when your program
  234.             returns to DOS.  Your program must close any open XMS handles
  235.             before quitting, or the XMS memory associated with the handles
  236.             will be unavailable to other programs.  Do not confuse this
  237.             subroutine with XMSFree, whick determines the XMS memory
  238.             available.
  239.  
  240. Returns:    if CF = 0, no error
  241.             if CF = 1, AH = XMS error code
  242. Uses:       AX, flags
  243. Example:    see example code at the end of this file
  244.  
  245.  
  246.  
  247. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  248.  
  249. ISEMS:      detects EMS driver
  250. Source:     isems.asm
  251.  
  252. Call with:  no parameters
  253. Returns:    if CF = 1, no Expanded Memory manager installed
  254.             if CF = 0, EMS memory is installed
  255. Uses:       CF
  256. Example:    see example code at the end of this file
  257.  
  258.  
  259.  
  260. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  261.  
  262. ISXMS:      detects XMS driver
  263. Source:     isxms.asm
  264. Call with:  no parameters
  265. Returns:    if CF = 1, no XMS driver is installed
  266.             if CF = 0, XMS memory is available
  267. Uses:       CF
  268. Example:    see example code at the end of this file
  269.  
  270.  
  271.  
  272. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  273.  
  274. XMGET:      copy data from XMS memory to system RAM
  275. Source:     xmputget.asm (xms.asm)
  276.  
  277. Call with:  BX = XMS handle
  278.             ES:[DI] pointing to destination buffer
  279.             DS:[SI] pointing to 4-byte offset in XMS block
  280.             DX:AX = number of bytes to copy
  281. Returns:    if CF = 0, no error
  282.             if CF = 1, AH = XMS error code
  283. Uses:       AX, flags
  284. Example:    see example code at the end of this file
  285.  
  286.  
  287.  
  288. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  289.  
  290. XMPUT:      copy data to XMS memory from system RAM
  291. Source:     xmputget.asm (xms.asm)
  292.  
  293. Call with:  BX = XMS handle
  294.             ES:[DI] pointing to data to copy
  295.             DS:[SI] pointing to 4-byte offset in XMS block
  296.             DX:AX = number of bytes to copy
  297. Returns:    if CF = 0, no error
  298.             if CF = 1, AH = XMS error code
  299. Uses:       AX, flags
  300. Example:    see example code at the end of this file
  301.  
  302.  
  303.  
  304.  
  305.  
  306. ; EXPANDED AND EXTENDED MEMORY EXAMPLE CODE
  307.  
  308. ; This example determines if EMS or XMS memory is installed, allocates
  309. ; 32k of EMS or XMS memory, copies a Herules graph to the allocated memory
  310. ; and later, copies the data back to the video buffer and releases
  311. ; the memory block
  312.  
  313. include asm.inc
  314.  
  315. public  herc2x
  316.  
  317. extrn   isems:proc, isxms:proc
  318. extrn   allocems:proc, allocxms:proc
  319. extrn   emput:proc, xmput:proc
  320. extrn   emget:proc, xmget:proc
  321. extrn   freeems:proc, freexms:proc
  322.  
  323. .data
  324. IF @codesize
  325. xalloc  dd 0
  326. xput    dd 0
  327. xget    dd 0
  328. xfree   dd 0
  329. ELSE
  330. xalloc  dw 0
  331. xput    dw 0
  332. xget    dw 0
  333. xfree   dw 0
  334. ENDIF
  335. xoffset dw 0,0
  336. xhandle dw 0
  337. xerror  dw 0
  338.  
  339. .code
  340. herc2x  proc
  341. ; program fragment assumes DS:@data
  342. ; set up default conditions: use EMS
  343.         mov     xerror,offset ems_error
  344.         mov     word ptr xalloc,offset allocems
  345.         mov     word ptr xput,offset emput
  346.         mov     word ptr xget,offset emget
  347.         mov     word ptr xfree,offset freeems
  348. IF @codesize
  349.         mov     ax,seg allocems
  350.         mov     word ptr xalloc+2,ax  ; all ASMLIB code in same segment
  351.         mov     word ptr xput+2,ax
  352.         mov     word ptr xget+2,ax
  353.         mov     word ptr xfree+2,ax
  354. ENDIF
  355. ; see if EMS is installed
  356.         call    isems
  357.         jnc     allocate_memory
  358.  
  359. ; EMS not installed - see if XMS memory is avaialble
  360. ; set up for XMS subroutines
  361.         mov     xerror,offset xms_error
  362.         mov     word ptr xalloc,offset allocxms
  363.         mov     word ptr xput,offset xmput
  364.         mov     word ptr xget,offset xmget
  365.         mov     word ptr xfree,offset freexms
  366. IF @codesize
  367.         mov     ax,seg allocxms
  368.         mov     word ptr xalloc+2,ax  ; all ASMLIB code in same segment
  369.         mov     word ptr xput+2,ax
  370.         mov     word ptr xget+2,ax
  371.         mov     word ptr xfree+2,ax
  372. ENDIF
  373.         call    isxms
  374.         jc      foiled_again         ; don't use EMS or XMS
  375.  
  376. ; allocate 32k
  377. allocate_memory:
  378.         mov     ax,32768
  379.         xor     dx,dx                ; DX:AX = 32768
  380.         call    xalloc               ; allocate EMS or XMS memory block
  381.         jc      xerror
  382.         mov     xhandle,bx           ; save the handle
  383.  
  384. ; copy the graph to EMS
  385.         mov     di,0B000h            ; Hercules buffer
  386.         mov     es,di
  387.         xor     di,di                ; ES:[BX] -> video buffer
  388.         mov     ax,32768             ; copy entire graph
  389.         lea     si,xoffset           ; start at offset 0 in memory block
  390.         call    xput                 ; copy the graph to memory
  391.         jc      xerror
  392.  
  393. ; later ...
  394. ; copy the graph back to the video buffer
  395.         mov     bx,xhandle
  396.         mov     dx,0B000h
  397.         mov     es,dx
  398.         xor     di,di                ; ES:[DI] points to destination
  399.         mov     ax,32768             ; copy all 32k
  400.         xor     dx,dx                ; DX:AX = 32768
  401.         lea     si,xoffset           ; start at offset 0 in memory block
  402.         call    xget                 ; copy the graph back to video buffer
  403.         jc      xerror
  404.  
  405. ; all done with graph copy; release the memory block
  406.         call    xfree
  407.         jc      xerror
  408.